home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 1998 November / IRIX 6.5.2 Base Documentation November 1998.img / usr / share / catman / p_man / cat3 / aio_read.z / aio_read
Text File  |  1998-10-20  |  12KB  |  199 lines
  1.  
  2.  
  3.  
  4. AAAAIIIIOOOO____RRRREEEEAAAADDDD((((3333))))                                                        AAAAIIIIOOOO____RRRREEEEAAAADDDD((((3333))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      aio_read, aio_read64 - asynchronous I/O read
  10.  
  11. CCCC SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  12.      ####iiiinnnncccclllluuuuddddeeee <<<<aaaaiiiioooo....hhhh>>>>
  13.  
  14.      iiiinnnntttt aaaaiiiioooo____rrrreeeeaaaadddd((((aaaaiiiiooooccccbbbb____tttt ****aaaaiiiiooooccccbbbbpppp))));;;;
  15.  
  16.      iiiinnnntttt aaaaiiiioooo____rrrreeeeaaaadddd66664444((((aaaaiiiiooooccccbbbb66664444____tttt ****aaaaiiiiooooccccbbbbpppp))));;;;
  17.  
  18. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  19.      The _aaaa_iiii_oooo______rrrr_eeee_aaaa_dddd_((((_)))) function allows the calling process to read aaaaiiiiooooccccbbbbpppp----
  20.      >>>>aaaaiiiioooo____nnnnbbbbyyyytttteeeessss from the file associated with aaaaiiiiooooccccbbbbpppp---->>>>aaaaiiiioooo____ffffiiiillllddddeeeessss into the
  21.      buffer pointed to by aaaaiiiiooooccccbbbbpppp---->>>>aaaaiiiioooo____bbbbuuuuffff (see rrrreeeeaaaadddd((((2222))))).  The function call
  22.      returns when the read request has been initiated or, at a minimum, queued
  23.      for the file or device.
  24.  
  25.      The aaaaiiiiooooccccbbbb---->>>>aaaaiiiioooo____ssssiiiiggggeeeevvvveeeennnntttt defines how the calling process will be notified
  26.      upon I/O completion.
  27.  
  28.      If ssssiiiiggggeeeevvvv____nnnnoooottttiiiiffffyyyy is SSSSIIIIGGGGEEEEVVVV____NNNNOOOONNNNEEEE, then no notification will be posted to the
  29.      calling application.
  30.  
  31.      If ssssiiiiggggeeeevvvv____nnnnoooottttiiiiffffyyyy is SSSSIIIIGGGGEEEEVVVV____SSSSIIIIGGGGNNNNAAAALLLL, then the signal specified in ssssiiiiggggeeeevvvv____ssssiiiiggggnnnnoooo
  32.      will be sent to the calling process. If SSSSAAAA____SSSSIIIIGGGGIIIINNNNFFFFOOOO is set for the signal
  33.      (see ssssiiiiggggaaaaccccttttiiiioooonnnn((((2222))))) and the signal is in the range of SSSSIIIIGGGGRRRRTTTTMMMMIIIINNNN and
  34.      SSSSIIIIGGGGRRRRTTTTMMMMAAAAXXXX then the signal will be queued to the process and the value in
  35.      ssssiiiiggggeeeevvvv____vvvvaaaalllluuuueeee will be the ssssiiii____vvvvaaaalllluuuueeee in the generated signal.
  36.  
  37.      If ssssiiiiggggeeeevvvv____nnnnoooottttiiiiffffyyyy is SSSSIIIIGGGGEEEEVVVV____CCCCAAAALLLLLLLLBBBBAAAACCCCKKKK then the function ssssiiiiggggeeeevvvv____ffffuuuunnnncccc will be
  38.      called with ssssiiiiggggeeeevvvv____vvvvaaaalllluuuueeee as the argument. Only one callback will be called
  39.      at a time, however programs should be careful to note that a callback may
  40.      be run in parallel with the calling process.
  41.  
  42.      If ssssiiiiggggeeeevvvv____nnnnoooottttiiiiffffyyyy is SSSSIIIIGGGGEEEEVVVV____TTTTHHHHRRRREEEEAAAADDDD then the function ssssiiiiggggeeeevvvv____nnnnoooottttiiiiffffyyyy____ffffuuuunnnnccccttttiiiioooonnnn
  43.      will be called by a new thread (see pppptttthhhhrrrreeeeaaaaddddssss((((5555))))) with ssssiiiiggggeeeevvvv____vvvvaaaalllluuuueeee as the
  44.      argument.  This thread is created when the event arrives with the
  45.      attributes specified in ssssiiiiggggeeeevvvv____nnnnoooottttiiiiffffyyyy____aaaattttttttrrrriiiibbbbuuuutttteeeessss except that it is
  46.      automatically detached.  The calling process should ensure there are
  47.      sufficient resources to create the thread.
  48.  
  49.      All aaaaiiiioooo____rrrreeeeaaaadddd(((()))) calls must supply a complete aaaaiiiiooooccccbbbb---->>>>aaaaiiiioooo____ssssiiiiggggeeeevvvveeeennnntttt
  50.      structure.
  51.  
  52.      The aaaaiiiiooooccccbbbbpppp---->>>>aaaaiiiioooo____lllliiiioooo____ooooppppccccooooddddeeee field is ignored by aaaaiiiioooo____rrrreeeeaaaadddd(((()))).
  53.  
  54.      Prioritized I/O is not currently supported among asynchronous file
  55.      operations.  aaaaiiiiooooccccbbbbpppp---->>>>aaaaiiiioooo____rrrreeeeqqqqpppprrrriiiioooo must be set to 0, otherwise the call
  56.      will fail.
  57.  
  58.  
  59.  
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. AAAAIIIIOOOO____RRRREEEEAAAADDDD((((3333))))                                                        AAAAIIIIOOOO____RRRREEEEAAAADDDD((((3333))))
  71.  
  72.  
  73.  
  74.      After a call to aaaaiiiioooo____rrrreeeeaaaadddd the aaaaiiiiooooccccbbbbpppp may be used as an argument to
  75.      aaaaiiiioooo____eeeerrrrrrrroooorrrr(((()))) and aaaaiiiioooo____rrrreeeettttuuuurrrrnnnn(((()))) in order to determine the error status and
  76.      return status, respectively, of the asynchronous operation while it is
  77.      proceeding. If an error condition is encountered during queueing, the
  78.      function call returns without having initiated or queued the request.
  79.      After a successful call to enqueue an asynchronous I/O operation, the
  80.      value of the file offset for the file is undefined.
  81.  
  82.      If the buffer pointed to by aaaaiiiiooooccccbbbbpppp---->>>>aaaaiiiioooo____bbbbuuuuffff or the control block pointed
  83.      to by aaaaiiiiooooccccbbbbpppp changes or becomes an illegal address prior to asynchronous
  84.      I/O completion then the behavior is undefined.  Simultaneous asynchronous
  85.      operations using the same aaaaiiiiooooccccbbbbpppp produce undefined results.
  86.  
  87.      For any system action that changes the process memory space while an
  88.      asynchronous I/O is outstanding to the address range being changed, the
  89.      result of that asynchronous I/O is undefined.
  90.  
  91.      The aaaaiiiioooo____rrrreeeeaaaadddd66664444() function is identical to aaaaiiiioooo____rrrreeeeaaaadddd(((()))) except that it takes
  92.      an aaaaiiiiooooccccbbbb66664444____tttt * (see <aaaaiiiioooo....hhhh>).  This structure allows for the
  93.      specification of a file offset greater than 2 Gigabytes.
  94.  
  95.  
  96. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  97.      aio_write(3), lio_listio(3), aio_error(3), aio_return(3), aio_hold(3),
  98.      aio_cancel(3), aio_sgi_init(3), aio_fsync(3), read(2), lseek(2),
  99.      close(2), _exit(2), exec(2), fork(2), pthreads(5), sysconf(3C).
  100.  
  101. DDDDIIIIAAAAGGGGNNNNOOOOSSSSTTTTIIIICCCCSSSS
  102.      The aaaaiiiioooo____rrrreeeeaaaadddd(((()))) returns the value 0 to the calling process if the I/O
  103.      operation is successfully queued; otherwise, the function shall return
  104.      the value -1 and shall set _e_r_r_n_o to indicate the error.
  105.  
  106.      [EAGAIN]       The requested asynchronous I/O operation was not queued
  107.                     due to system resource limitations. Often this is due to
  108.                     exceeding the maximum number of asynchronous I/O
  109.                     operations for the system. The maximum can be checked with
  110.                     a call to _s_y_s_c_o_n_f() with an argument of ____SSSSCCCC____AAAAIIIIOOOO____MMMMAAAAXXXX....
  111.  
  112.      Each of the following conditions may be detected synchronously at the
  113.      time of the call to aaaaiiiioooo____rrrreeeeaaaadddd(((()))) , or asynchronously. If any of the
  114.      conditions below are detected synchronously at the time of the call, the
  115.      aaaaiiiioooo____rrrreeeeaaaadddd(((()))) function shall return -1 and set _e_r_r_n_o to the corresponding
  116.      value. If any of the conditions below are detected asynchronously, the
  117.      return status of the asynchronous operation shall be set to -1 and the
  118.      error status of the asynchronous operation shall be set to the
  119.      corresponding value.
  120.  
  121.      [EBADF]        The aaaaiiiiooooccccbbbbpppp---->>>>aaaaiiiioooo____ffffiiiillllddddeeeessss argument is not a valid file
  122.                     descriptor open for reading.
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. AAAAIIIIOOOO____RRRREEEEAAAADDDD((((3333))))                                                        AAAAIIIIOOOO____RRRREEEEAAAADDDD((((3333))))
  137.  
  138.  
  139.  
  140.      [EINVAL]       The file offset value implied by aaaaiiiiooooccccbbbbpppp---->>>>aaaaiiiioooo____ooooffffffffsssseeeetttt would
  141.                     be invalid, aaaaiiiiooooccccbbbbpppp---->>>>aaaaiiiioooo____rrrreeeeqqqqpppprrrriiiioooo is not a valid value, or
  142.                     aaaaiiiiooooccccbbbbpppp---->>>>aaaaiiiioooo____nnnnbbbbyyyytttteeeessss is an invalid value.
  143.  
  144.      In the case that the aaaaiiiioooo____rrrreeeeaaaadddd(((()))) successfully queues the I/O operation,
  145.      the return status of the asynchronous operation shall be one of the
  146.      values normally returned by the _r_e_a_d(_2) function call. If the operation
  147.      is successfully queued, but is subsequently canceled or encounters an
  148.      error, the error status for the asynchronous operation shall contain one
  149.      of the values normally set by the _r_e_a_d(_2) function call, or one of the
  150.      following:
  151.  
  152.      [EBADF]        The aaaaiiiiooooccccbbbbpppp---->>>>aaaaiiiioooo____ffffiiiillllddddeeeessss argument is not a valid file
  153.                     descriptor open for reading.
  154.  
  155.      [EINVAL]       The file offset value implied by aaaaiiiiooooccccbbbbpppp---->>>>aaaaiiiioooo____ooooffffffffsssseeeetttt would
  156.                     be invalid.
  157.  
  158.      [ECANCELED]    The requested I/O was canceled before the I/O completed
  159.                     due to an explicit aaaaiiiioooo____ccccaaaannnncccceeeellll((((3333)))) request.
  160.  
  161.  
  162.  
  163.  
  164.  
  165.  
  166.  
  167.  
  168.  
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.